Command:

Translate a DES or HMAC key from encryption under an LMK pair to encryption under a public key. A signature is optionally generated over the encrypted Key

Notes:

This command requires the optional RSA licence, error code 67 will be returned if the command is not licenced.

This command does not require Authorised State, and does not refer to the Key Type Table for export.

See: Using the RSA cryptosystem for details of where valid values of the common parameters can be found.

Field

Length & Type

Details

COMMAND MESSAGE

Message Header

m A

Will be returned to the Host unchanged

Command Code

2 A

Value GK

Encryption Identifier

2 N

Identifier of algorithm used to encrypt the key

Mask Generation Function

2 N

01 = MGF1 as defined in PKCS#1 v2.0

Optional, only present if PAD Mode Identifier is 02 (OAEP).

MGF Hash Function

2 N

01 = SHA-1
Optional, only present if PAD Mode Identifier is 02 (OAEP). This field defines the hash function to be used in the MGF.

OAEP Encoding Parameters Length

2 N

Optional, only present if PAD Mode Identifier is 02 (OAEP).

OAEP Encoding Parameters

n B

Optional, only present if PAD Mode Identifier is 02 (OAEP).

If present, this field should be encoded according to Reference 1 section 11.2.1. The HSM does not interpret or validate the contents of this field. If OAEP padding is used, but no Encoding Parameters are provided, then OAEP Parameters Length should be 00, and this field will be empty.

OAEP Encoding Parameters Delimiter

1 A

;
Optional, only present if PAD Mode Identifier is 02 (OAEP)

Key Type

4 N

Key type; used to indicate LMK pair and variant used to encrypt the key).

For HMAC keys, Key Type should have the value 3401.

Signature Indicator

1 A

=
Only present if the following signature related fields are also present.

Signature Hash Identifier

2 A

Identifier of the hash algorithm used to hash the message.

Signature Identifier

2 A

Identifier of the signature algorithm used to sign the message.

Signature Pad Mode Identifier

2 N

Identifier of the Pad Mode to be used in the signature process.

01 = PKCS#1 v1.5 method (EME-PKCS1-v1_5)

Only present if Signature Indicator above is present.

Header Data Block Length

4 N

Length (in byte) of following field. If no Header Data Block is to be supplied, then this field should be set to 0000.

Only present if Signature Indicator above is present.

Header Data Block

n B

Block of data to be pre-pended to the encrypted key, prior to signing.

Only present if Signature Indicator above is present.

Delimiter

1 A

;

Only present if Signature Indicator above is present.

Footer Data Block Length

4 N

Length (in byte) of following field. If no Footer Data Block is to be supplied, then this field should be set to 0000

Only present if Signature Indicator above is present.

Footer Data Block

n B

Block of data to be appended to the encrypted key, prior to signing.

Only present if Signature Indicator above is present.

Delimiter

1 A

;

Only present if Signature Indicator above is present.

Footer Data Block Length

4 N

Length (in byte) of following field. If no Footer Data Block is to be supplied, then this field should be set to 0000

Only present if Signature Indicator above is present.

Footer Data Block

n B

Block of data to be appended to the encrypted key, prior to signing.

Only present if Signature Indicator above is present.

Delimiter

1 A

;

Only present if Signature Indicator above is present.

Private Key Flag

2 N

Flag to indicate location of the private key;

if flag = 99 use private key provided with command

else flag = index of stored private key

Only present if Signature Indicator above is present.

Private Key Length

4 N

Length (in bytes) of the following field (only present if flag = 99)

Only present if Signature Indicator above is present.

Private Key

n B

Private key, encrypted using LMK pair 34-35 (only present if flag = 99)

Only present if Signature Indicator above is present.

DES Key Flag

1 N

Flag to indicate length of DES key

0 : single length
1 : double length
2 : triple length

Only present when exporting a DES key.

DES Key (LMK)

16H or 32H or
1A+32H or 1A+48H

DES key, encrypted under LMK pair indicated by Key Type (length indicated by DES key flag)

Only present when exporting a DES key (Key Type <> 3401).

Check Value

16 H

Check value on DES key.

Only present when exporting a DES key (Key Type <> 3401).

HMAC Key Block Format

2 N

The format of the HMAC key block when stored encrypted under the LMK. The only value currently supported is 00.

Only present if importing an HMAC key (i.e. Key Type = 3401).

HMAC Key Length

4 N

Length in bytes of the next field.

Only present when exporting an HMAC key (Key Type = 3401).

HMAC Key (LMK)

N B

HMAC Key, encrypted under LMK pair 34-35 variant 1

Only present when exporting an HMAC key (Key Type = 3401).

MAC

4 B

MAC on public key and authentication data, calculated using LMK pair 36-37

Public Key

n B

Public key, DER encoded in ASN.1 format (sequence of modulus, exponent)

Authentication Data

n B

Optional; additional data included in the MAC calculation (must not include ;)

Delimiter

1 A

;

Only present if the Key Block Type below is present.
 

Key Block Template Length

4 N

Length of Key Block data.

Optional, only present if Key Block Type = 02.

Key Block Template

n H

Key Block, DER encoded in ASN.1 format. Key data and Check Value data (if present) zero filled.

Optional, only present if Key Block Type = 02.

Delimiter

1 A

;

Optional, only present if Key Block Type = 02.

Key Offset

4 N

Offset to the position within the Key Block to insert the key.

Optional, only present if Key Block Type = 02.

Check Value Length

2 N

Length in bytes of Check Value field. Permitted values are 0..8.

If no check value is required then this field should be set to 0.
If a check value length is specified, then the HSM will generate a check value and include it in the Key Block, inserted at the position indicated by Check Value Offset.

Optional, only present when exporting DES keys and if Key Block Type = 02.

Check Value Offset

4 N

Offset to the position within the Key Block to insert a check value. If Check Value length is 0, then this field is ignored.

Optional, only present when exporting DES keys and if Key Block Type = 02.

End Message Delimiter

1 C

Optional. Must be present if a message trailer is present. Value X'19

Field

Length & Type

Details

RESPONSE MESSAGE

Message header

m A

Returned to the Host unchanged.

Response code

2 A

Value GL.

Error code

2 N

00 : No error

01 : MAC verification failure

02 : Check value verification failure

03 : Invalid secret key type

04 : Invalid secret key flag

05 : Invalid DES key type

06 : Invalid encryption identifier

07 : Invalid pad mode identifier

10 : DES Key parity error

13 : LMK error ; report to supervisor

15 : Error in input data

36 : Invalid HMAC key block format value

38 : Invalid HMAC key length

47 : DSP error; report to supervisor

49 : Secret key error; report to supervisor

50 : Public key does not conform to encoding rules

51 : Invalid signature hash identifier

52 : Invalid signature identifier

53 : Invalid signature pad mode identifier

54 : Header Data Block error

55 : Footer Data Block error

56 : Invalid DES Key Flag

67 : Command not licenced

74 : Invalid Digest Info syntax (no hash mode only)

67 : Command not licenced

76 : Key Block length error

78 : Secret key Length error

81: Invalid Key Block type

83 : Key block format error

84 : Key block check value error

85 : Invalid OAEP Mask Generation Function

86 : Invalid OAEP MGF Hash Function

87 : OAEP Parameter Error

88 : OAEP Error

Initialization value

16 H

Initialization value for DES key

Only present when exporting a DES key (i.e. Key Type <> 3401)

Encrypted Key Length

4 N

Length (in bytes) of the next field.

Encrypted Key

n B

Key, encrypted under the public key.

Signature Length

4 N

Length (in bytes) of the next field.

Only present when the Signature Indicator is present.

Signature

n B

Signature of concatenation of header data block, encrypted key, and footer data block.

Only present when the Signature Indicator is present.

End message delimiter

1 C

Present only if present in the command message. Value X19.